Fox's Git Mirrors
docs/catalog-spec.md HEAD (ed7be254) Text, 8.06 KB
Catalog Specification — Agent Bundles
Version: 1.0.0
This document is the authoritative specification for Omegon agent bundles in the armory catalog. All agents in the catalog must conform to this spec.
Overview
An agent bundle is a directory under T383838catalog/<agent-id>/ containing a manifest and associated files. Agents are installed via T383838omegon catalog install, which fetches from this registry and writes to T383838~/.omegon/catalog/<agent-id>/.
Directory Structure
T282828
catalog/
└── styrene.bd-agent/ # Directory name matches the agent ID
├── agent.toml # TOML manifest (required)
├── agent.pkl # Pkl manifest (optional — enables amends inheritance)
├── PERSONA.md # Persona directive (required)
└── mind/
└── facts.jsonl # Seed knowledge facts (optional)
catalog-registry.toml
T383838catalog-registry.toml at the repo root is the index that T383838omegon catalog install fetches first. It maps each agent ID to its metadata and file list.
Format
T282828
["styrene.bd-agent"]
name = "Business Development"
version = "1.0.0"
domain = "ops"
description = "Short description of what this agent does."
files = ["agent.toml", "agent.pkl", "PERSONA.md", "mind/facts.jsonl"]
TOML Key Quoting — Required
Agent IDs contain dots (e.g. T383838styrene.bd-agent). In TOML, an unquoted dotted table header like T383838[styrene.bd-agent] is interpreted as nested tables — equivalent to T383838[styrene] with a sub-key T383838bd-agent. This causes a parse error when T383838omegon deserializes the registry.
Always quote agent IDs in table headers:
T282828
# Correct — literal key "styrene.bd-agent"
["styrene.bd-agent"]
files = [...]
# Wrong — TOML parses as nested tables, omegon will error
[styrene.bd-agent]
files = [...]
This applies to any entry whose ID contains a dot. Simple single-word IDs (no dots) do not need quoting.
Fields
┌─────────────┬──────────┬─────────────────────────────────────────────────────────────────────────┐
│ Field │ Required │ Description │
├─────────────┼──────────┼─────────────────────────────────────────────────────────────────────────┤
│ T383838name │ Yes │ Human-readable display name │
│ T383838version │ Yes │ Semantic version (T383838MAJOR.MINOR.PATCH) │
│ T383838domain │ Yes │ Agent domain — see domains
id = "styrene.bd-agent" # Must match the directory name and registry key
name = "Business Development"
version = "1.0.0"
description = "..."
domain = "ops"
[persona]
directive = "PERSONA.md"
badge = "bd" # Optional emoji/short badge for UI display
mind_facts = ["mind/facts.jsonl"] # One or more JSONL facts files
[[extensions]]
name = "vox"
version = ">=0.3.0"
[settings]
model = "anthropic:claude-sonnet-4-6"
thinking_level = "low" # off | minimal | low | medium | high
context_class = "squad" # squad | maniple | clan | legion
max_turns = 50
[workflow]
name = "doc-standard"
[secrets]
required = ["ANTHROPIC_API_KEY"]
optional = ["GOOGLE_OAUTH_TOKEN"]
[secrets.env]
GOOGLE_APPLICATION_CREDENTIALS = "GOOGLE_APPLICATION_CREDENTIALS"
[[triggers]]
name = "weekly-status-report"
schedule = "weekly" # hourly | daily | weekdays | weekly
template = "..."
`f`b
>>>Domains
`c
┌───────────────┬────────────────────────────────────────────────┐
│ Domain │ Use │
├───────────────┼────────────────────────────────────────────────┤
│ `BT383838`Fdddchat`f`b │ Conversational agents (Discord, Slack bridges) │
│ `BT383838`Fdddcoding`f`b │ Software engineering agents │
│ `BT383838`Fdddcoding-python`f`b │ Python-focused coding agents │
│ `BT383838`Fdddcoding-rust`f`b │ Rust-focused coding agents │
│ `BT383838`Fdddinfra`f`b │ Infrastructure / DevOps agents │
│ `BT383838`Fdddops`f`b │ Business operations agents │
│ `BT383838`Fdddfull`f`b │ General-purpose agents with full tooling │
└───────────────┴────────────────────────────────────────────────┘
`a
>>>Secrets
Agent bundle `BT383838`Fddd[secrets]`f`b sections follow the same names-only contract as plugin manifests:
`BT282828`Fddd
[secrets]
required = ["ANTHROPIC_API_KEY"]
optional = ["VAULT_ROOT_TOKEN"]
[secrets.env]
VAULT_TOKEN = "VAULT_ROOT_TOKEN"
`f`b
Use `BT383838`Fdddrequired`f`b and `BT383838`Fdddoptional`f`b for Omegon secret names, and `BT383838`Fddd[secrets.env]`f`b for environment variables that should be projected for profiled/headless agent runs. Values must be secret names or balanced single-template references such as `BT383838`Fddd{VAULT_ROOT_TOKEN}`f`b, never raw credential values. One-sided braces are invalid, and public payload linting remains the second gate for obvious secret-shaped values.
-
>>agent.pkl — Pkl Manifest (Optional)
If `BT383838`Fdddagent.pkl`f`b is present alongside `BT383838`Fdddagent.toml`f`b, it enables `!Pkl-native agent inheritance`!. Users can create overlay files that extend the base agent without replacing it:
`BT282828`Fddd
// user-overlay.pkl
amends "omegon://catalog/styrene.bd-agent/agent.pkl"
persona {
mind_facts { ...super; "mind/personal_facts.jsonl" }
directive_extend { "PERSONA.personal.md" }
}
settings {
thinking_level = "medium"
}
`f`b
Pkl manifests must use the `BT383838`Fdddomegon://schema/AgentManifest.pkl`f`b URI, not a relative path:
`BT282828`Fddd
// Correct
amends "omegon://schema/AgentManifest.pkl"
// Wrong — resolves relative to the file; fails when installed to ~/.omegon/catalog/
amends "AgentManifest.pkl"
`f`b
The `BT383838`Fdddomegon://`f`b scheme is served by a custom module reader embedded in the binary. `BT383838`Fdddomegon://schema/<name>`f`b serves compiled-in schema files; `BT383838`Fdddomegon://catalog/<id>/path`f`b serves files from `BT383838`Fddd~/.omegon/catalog/<id>/`f`b.
>>>Workflow Phases in Pkl
When defining workflow phases in a Pkl manifest, the `BT383838`FdddMapping`f`b type requires explicit construction syntax. The shorthand block syntax does not work for null-initialized optional mappings:
`BT282828`Fddd
// Correct
workflow = new WorkflowConfig {
name = "doc-standard"
phases = new Mapping<String, PhaseConfig> {
["drafting"] = new { model = "anthropic:claude-sonnet-4-6"; max_turns = 40 }
["reviewing"] = new { model = "anthropic:claude-sonnet-4-6"; max_turns = 20 }
}
}
// Wrong — shorthand block syntax on nullable Mapping
workflow {
name = "doc-standard"
phases {
["drafting"] { model = "anthropic:claude-sonnet-4-6" }
}
}
`f`b
-
>>PERSONA.md
The persona directive is free-form Markdown. Conventions:
• Open with a `BT383838`Fddd# Agent Name`f`b heading
• Group responsibilities under `BT383838`Fddd##`f`b headings
• Include an `BT383838`Fddd## Operating principles`f`b section for behavior constraints — things the agent must do or avoid regardless of user instruction
• Include a `BT383838`Fddd## Communication style`f`b section
Keep it action-oriented. The runtime prepends identity metadata automatically; don't repeat name/version/domain information that's already in the manifest.
-
>>mind/facts.jsonl
Seed facts are loaded into the agent's working memory at session start. Each line is a JSON object:
`BT282828`Fddd
{"section":"Category Name","content":"The fact or rule.","confidence":1.0}
`f`b
`c
┌────────────┬──────────┬──────────────────────────────────────────────────────────────────────────┐
│ Field │ Required │ Description │
├────────────┼──────────┼──────────────────────────────────────────────────────────────────────────┤
│ `BT383838`Fdddsection`f`b │ Yes │ Grouping label (e.g. `BT383838`Fddd"Reporting"`f`b, `BT383838`Fddd"Opportunity Assessment"`f`b) │
│ `BT383838`Fdddcontent`f`b │ Yes │ The fact, rule, or procedure │
│ `BT383838`Fdddconfidence`f`b │ Yes │ Float `BT383838`Fddd0.0`f`b–`BT383838`Fddd1.0`f`b. Use `BT383838`Fddd1.0`f`b for definitive rules, `BT383838`Fddd0.9`f`b for strong conventions… │
└────────────┴──────────┴──────────────────────────────────────────────────────────────────────────┘
`a
Keep facts atomic — one rule per line. Multi-step procedures are better as a numbered list within a single `BT383838`Fdddcontent`f`b string than spread across multiple facts.
-
>>Adding an Agent to the Catalog
1. Create `BT383838`Fdddcatalog/<agent-id>/`f`b with the required files
2. Add a quoted entry to `BT383838`Fdddcatalog-registry.toml`f`b:
`BT282828`Fddd
["your-org.agent-name"]
name = "..."
version = "1.0.0"
domain = "..."
description = "..."
files = ["agent.toml", "PERSONA.md"]
`f`b
3. Update `BT383838`Fdddcatalog.rs`f`b in omegon to add the agent to `BT383838`FdddBUNDLED`f`b for airgap support
4. Submit a PR — include a brief description of the agent's purpose and target user
<
-
`a`F666`[Served by rngit 1.5.2`:/page/index.mu] - Generated in 0.03s`f